package com.ruoyi.web.controller.post.service;

import java.util.List;
import com.ruoyi.web.controller.post.domain.Post;
import com.ruoyi.web.controller.post.domain.PostRecommendationHistory;

/**
 * 帖子推荐Service接口（增强版）
 *
 * @author thunderhub
 */
public interface IPostRecommendationService
{
    /**
     * 获取推荐帖子列表（按点赞数排序，排除用户访问过的）
     *
     * @param userId 用户ID，如果为null则表示未登录用户
     * @param limit 推荐数量限制
     * @return 推荐帖子列表
     */
    public List<Post> getRecommendedPostsByLikes(Long userId, int limit);

    /**
     * 获取推荐帖子列表（支持分类和关键词筛选）
     *
     * @param userId 用户ID，如果为null则表示未登录用户
     * @param limit 推荐数量限制
     * @param category 分类筛选
     * @param keyword 关键词筛选
     * @return 推荐帖子列表
     */
    public List<Post> getRecommendedPostsByLikesWithFilter(Long userId, int limit, String category, String keyword);

    /**
     * 获取智能推荐帖子（支持分类和关键词筛选）
     *
     * @param userId 用户ID
     * @param limit 推荐数量限制
     * @param userTags 用户感兴趣的标签（可选）
     * @param category 分类筛选
     * @param keyword 关键词筛选
     * @return 推荐帖子列表
     */
    public List<Post> getSmartRecommendedPostsWithFilter(Long userId, int limit, String userTags, String category, String keyword);

    /**
     * 根据用户偏好获取推荐帖子（支持分类和关键词筛选）
     *
     * @param userId 用户ID
     * @param limit 推荐数量限制
     * @param category 分类筛选
     * @param keyword 关键词筛选
     * @return 推荐帖子列表
     */
    public List<Post> getPersonalizedRecommendedPostsWithFilter(Long userId, int limit, String category, String keyword);

    /**
     * 记录用户访问帖子历史
     *
     * @param userId 用户ID
     * @param postId 帖子ID
     * @param visitType 访问类型（0=查看详情 1=推荐点击）
     * @return 结果
     */
    public int recordUserVisit(Long userId, Long postId, String visitType);

    /**
     * 检查用户是否访问过某个帖子
     *
     * @param userId 用户ID
     * @param postId 帖子ID
     * @return 是否访问过
     */
    public boolean hasUserVisited(Long userId, Long postId);

    /**
     * 获取用户访问过的帖子ID列表
     *
     * @param userId 用户ID
     * @return 帖子ID列表
     */
    public List<Long> getVisitedPostIds(Long userId);

    /**
     * 获取用户最近访问的帖子历史
     *
     * @param userId 用户ID
     * @param limit 查询数量限制
     * @return 访问历史列表
     */
    public List<PostRecommendationHistory> getRecentVisitHistory(Long userId, int limit);

    /**
     * 清理用户过期的访问记录
     *
     * @param userId 用户ID
     * @param days 保留天数，超过此天数的记录将被删除
     * @return 删除的记录数
     */
    public int cleanExpiredVisitHistory(Long userId, int days);

    /**
     * 获取智能推荐帖子（综合考虑点赞数、发布时间、标签相似度等因素）
     *
     * @param userId 用户ID
     * @param limit 推荐数量限制
     * @param userTags 用户感兴趣的标签（可选）
     * @return 推荐帖子列表
     */
    public List<Post> getSmartRecommendedPosts(Long userId, int limit, String userTags);

    /**
     * 根据用户偏好获取推荐帖子（基于用户历史访问的标签）
     *
     * @param userId 用户ID
     * @param limit 推荐数量限制
     * @return 推荐帖子列表
     */
    public List<Post> getPersonalizedRecommendedPosts(Long userId, int limit);
}